FAQ.md (1)

126-126: Optional: deep-link to the specific anchor for consistency.

Other pages updated in this PR (Packages.md, howto/Metrics.md) link to /integrations/#circuit-breaker--resilience. Using the same anchor here avoids sending readers to the top of a long page.

✏️ Proposed diff

-ColdBrew now provides a pluggable executor hook (`interceptors.SetDefaultExecutor`) for circuit breaking. Use [failsafe-go](https://github.com/failsafe-go/failsafe-go) as the recommended resilience library. See the [integrations page](/integrations/) for setup examples.
+ColdBrew now provides a pluggable executor hook (`interceptors.SetDefaultExecutor`) for circuit breaking. Use [failsafe-go](https://github.com/failsafe-go/failsafe-go) as the recommended resilience library. See the [integrations page](/integrations/#circuit-breaker--resilience) for setup examples.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@FAQ.md` at line 126, Update the integrations link in the FAQ.md line that
mentions the pluggable executor hook (interceptors.SetDefaultExecutor) so it
deep-links to the circuit breaker section; replace "/integrations/" with
"/integrations/#circuit-breaker--resilience" so users land directly on the
circuit-breaker--resilience anchor instead of the top of the integrations page.

integrations.md (2)

296-316: Nit: lazy-construction under the lock is fine, but consider sync.Map or a pre-built map to avoid lock contention on the hot path.

The current pattern acquires mu on every protected call just to look up (and, once, create) the breaker. For a hot client path this becomes a global contention point. Two simple alternatives:

• Pre-build all breakers once in init() (since configs is static) and read from the map lock-free.
• Use sync.Map or a sync.RWMutex with a fast read path.

♻️ Pre-built map variant

-    var (
-        mu       sync.Mutex
-        breakers = make(map[string]circuitbreaker.CircuitBreaker[any])
-    )
+    breakers := make(map[string]circuitbreaker.CircuitBreaker[any], len(configs))
+    for method, cfg := range configs {
+        breakers[method] = circuitbreaker.NewBuilder[any]().
+            WithFailureThreshold(cfg.failureThreshold).
+            WithDelay(cfg.delay).
+            Build()
+    }

     interceptors.SetDefaultExecutor(func(ctx context.Context, method string, fn func(ctx context.Context) error) error {
-        cfg, ok := configs[method]
-        if !ok {
+        cb, ok := breakers[method]
+        if !ok {
             return fn(ctx) // no circuit breaker for unconfigured methods
         }
-
-        mu.Lock()
-        cb, exists := breakers[method]
-        if !exists {
-            cb = circuitbreaker.NewBuilder[any]().
-                WithFailureThreshold(cfg.failureThreshold).
-                WithDelay(cfg.delay).
-                Build()
-            breakers[method] = cb
-        }
-        mu.Unlock()
-
         return failsafe.With[any](cb).WithContext(ctx).Run(func() error {
             return fn(ctx)
         })
     })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@integrations.md` around lines 296 - 316, The interceptor's hot path currently
locks mu inside interceptors.SetDefaultExecutor to lookup/create
breakers[method], causing contention; change to pre-build the breakers map once
(using configs to construct each circuitbreaker via circuitbreaker.NewBuilder
and store in breakers) before registering the executor so the executor can read
breakers lock-free, or replace breakers+mu with a sync.Map (or use a
sync.RWMutex with an RLock fast-path) and only write when creating a new
breaker; update the executor so it only reads from breakers without holding mu
and keeps the failsafe.With(...).Run usage unchanged.

---

242-354: Minor: code snippets omit imports.

Across the four examples, time, sync, context, and codes (from google.golang.org/grpc/codes, used by WithExcludedCodes) are used without being shown in any import (...) block. For copy-paste friendliness, consider adding the imports to the first example or a short "imports used in this page" note near the top of the section.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@integrations.md` around lines 242 - 354, The examples omit required imports
(time, sync, context and grpc codes) which makes copy-paste fail; update the
first example (or add a short "imports used in this page" note) to include the
missing packages—add time, context, sync and google.golang.org/grpc/codes
alongside the existing github.com/failsafe-go/failsafe-go,
github.com/failsafe-go/failsafe-go/circuitbreaker and
github.com/go-coldbrew/interceptors so all snippets (including functions init(),
the per-method breakers using mu/breakers, and any usage of WithExcludedCodes)
compile when copied.

howto/Metrics.md (1)

142-150: Optional: clarify placeholder variables in the circuit breaker example.

The snippet references circuitStateGauge and commandName without definition, and uses time.Second without showing imports. A brief comment above the block (e.g. "circuitStateGauge is a user-defined *prometheus.GaugeVec; commandName identifies the protected call") would help readers copy-paste the example with fewer surprises.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@howto/Metrics.md` around lines 142 - 150, Add a short explanatory comment
above the circuit breaker example clarifying that circuitStateGauge is a
user-defined *prometheus.GaugeVec used to export breaker state, commandName is
the string identifying the protected call, and that time.Second requires
importing the time package; leave the example code unchanged (symbols to
reference: circuitStateGauge, commandName, time.Second,
circuitbreaker.NewBuilder).

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes